<!-- 文档分类: OPS-MAN-004 | 阶段: 运维 | 原路径: docs/指南/claude-code-代理配置.md -->

通过 KHY 代理接入 Claude Code#

KHY 的 AI Gateway 代理服务器可以将 Kiro、Trae、Codex 等 IDE 适配器中的模型（DeepSeek、GPT-5.3、Claude 等）暴露为 Anthropic Messages API，让 Claude Code 直接使用。

工作原理#

Claude Code
  ↓  POST /v1/messages (Anthropic SSE)
KHY Proxy (127.0.0.1:9100)
  ↓  协议转换 + 适配器级联
kiro / trae / codex / ollama / ...
  ↓  实际模型（DeepSeek、GPT-5.3 等）
流式响应 → Anthropic SSE → Claude Code

• Claude Code 以为自己在调用 Claude 模型，实际由 KHY 透明代理到可用的 IDE 适配器
• 适配器级联优先级：kiro → cursor → trae → claude → codex → ollama → relay_api → api
• 每个适配器自动选择最佳可用模型，无需手动指定

推荐：khy claude 一键启动（零残留）#

下面「快速开始」一节是手动配置环境变量的底层路径，便于你理解原理。日常使用更推荐一条命令 khy claude——它自动把代理相关环境变量只注入到子进程里再拉起 claude，不写任何 settings.json、不污染你原生的 claude 认证：你退出后，直接敲 claude 仍然用回原来的官方账号。

khy claude            # 用 KHY 网关拉起 Claude Code（零残留 env 注入）
khy claude --list     # 只列出当前可用模型后退出
khy claude --model kiro/claude-sonnet-4.6   # 指定主模型直接启动

混合模式：主模型与子智能体分走不同来源#

当你手里有外部 Anthropic 官方额度（ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 不以 khy- 开头）时，可以让「主控模型」和「子智能体（sub-agent）」走不同来源，省着用官方额度：

混合模式要求你已配置外部 Anthropic 认证；若检测到只有 khy- 开头的 token，会自动回退为普通模式并给出提示。

--marshal：皇权特许，强制任命任意在线模型为主控#

khy claude --marshal kiro/claude-opus-4.6   # 强制把某个在线模型任命为「元帅」（主控）

--marshal 注入 KHY_MARSHAL，只校验该模型在线且协议可用，不做能力门控——把任意在线模型抬为主控控制器。

实现：Python 启动器 platform/khy_platform/cli.py（_run_claude_code_launcher、_build_khy_proxy_env）。它把 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / 模型变量等只 update 进子进程 env 后 subprocess.run，从不落盘——这正是「零残留」的代码依据。

快速开始#

1. 安装 / 更新 KHY#

pip install khy-os --upgrade

首次启动会自动初始化（安装 npm 依赖、生成配置、初始化数据库）：

khy

2. 启动代理服务器#

khy proxy start

启动后会打印 auth token 和监听地址：

[Proxy] Auto-generated auth token: khy-a1b2c3d4e5f6...
[Proxy] Listening on http://127.0.0.1:9100

忘记 token 可随时运行 khy proxy status 查看。

3. 配置 Claude Code 环境变量#

Linux / macOS#

export ANTHROPIC_BASE_URL=http://127.0.0.1:9100
export ANTHROPIC_API_KEY=khy-你的token
claude

写入 ~/.bashrc 或 ~/.zshrc 永久生效：

echo 'export ANTHROPIC_BASE_URL=http://127.0.0.1:9100' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY=khy-你的token' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell)#

临时生效：

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:9100"
$env:ANTHROPIC_API_KEY = "khy-你的token"
claude

永久生效（写入用户环境变量，需重开终端）：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://127.0.0.1:9100", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "khy-你的token", "User")

4. 验证#

# 检查代理健康状态
curl http://127.0.0.1:9100/health

# 查看可用模型列表
curl -H "Authorization: Bearer khy-你的token" http://127.0.0.1:9100/v1/models

指定特定模型（可选）#

默认情况下，Claude Code 发送的请求会由 KHY 自动级联到第一个可用的 IDE 适配器，适配器自动选择最佳模型。

如需精确控制，可以设置 ANTHROPIC_MODEL 环境变量，使用 适配器/模型名 语法：

# 使用 Trae 中的 DeepSeek
export ANTHROPIC_MODEL=trae/deepseek-v3

# 使用 Codex 中的 GPT-5.3
export ANTHROPIC_MODEL=codex/gpt-5.3-codex

# 使用 Kiro 中的模型
export ANTHROPIC_MODEL=kiro/claude-sonnet-4.6

# 使用本地 Ollama 模型
export ANTHROPIC_MODEL=ollama/qwen2.5:32b

也可通过 PROXY_MODEL_ROUTE_MAP 环境变量配置自定义路由规则：

# 将所有 claude-sonnet 请求路由到 trae 的 deepseek
export PROXY_MODEL_ROUTE_MAP='claude-sonnet-4-*=trae:deepseek-v3'

代理管理#

khy proxy start       # 启动代理（默认端口 9100）
khy proxy stop        # 停止代理
khy proxy status      # 查看代理状态和 auth token
khy proxy token       # 管理 auth token
khy proxy client add <名称>  # 为新客户端创建专属 token

自定义端口：

PROXY_PORT=8080 khy proxy start

支持的协议#

KHY 代理同时支持多种 API 协议，不同客户端可以通过同一个代理接入：

常见问题#

代理启动后 Claude Code 报 401#

检查 ANTHROPIC_API_KEY 是否与 khy proxy status 显示的 token 一致。

Claude Code 无响应#

1. 确认代理在运行：curl http://127.0.0.1:9100/health
2. 确认有可用适配器：在 KHY REPL 中运行 /model 或 khy gateway status
3. 检查 IDE（Kiro/Trae）是否已登录

Windows 上 Trae/Kiro 模型未检测到#

确保对应 IDE 已安装并登录。KHY 通过读取 IDE 的本地 storage 文件自动发现 token：

• Kiro: %APPDATA%/Kiro/
• Trae: %APPDATA%/Trae/

想用其他端口#

PROXY_PORT=8443 khy proxy start
# 相应修改 ANTHROPIC_BASE_URL
export ANTHROPIC_BASE_URL=http://127.0.0.1:8443